<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="sqlite3-Connection-Objects.html" />
<link rel="prev" href="module-sqlite3.html" />
<link rel="parent" href="module-sqlite3.html" />
<link rel="next" href="sqlite3-Connection-Objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>13.13.1 Module functions and constants</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.13 sqlite3  "
  href="module-sqlite3.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="13.13 sqlite3  "
  href="module-sqlite3.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="13.13.2 connection Objects"
  href="sqlite3-Connection-Objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sqlite3.html">13.13 sqlite3  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sqlite3.html">13.13 sqlite3  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="sqlite3-Connection-Objects.html">13.13.2 Connection Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION00151310000000000000000"></a><a name="sqlite3-Module-Contents"></a>
<br>
13.13.1 Module functions and constants
</h2>

<p>
<dl><dt><b><tt id='l2h-2552' xml:id='l2h-2552'>PARSE_DECLTYPES</tt></b></dt>
<dd>
This constant is meant to be used with the <var>detect_types</var> parameter of the
<tt class="function">connect</tt> function.

<p>
Setting it makes the <tt class="module">sqlite3</tt> module parse the declared type for each column it
returns.  It will parse out the first word of the declared type, i. e. for
"integer primary key", it will parse out "integer". Then for that column, it
will look into the converters dictionary and use the converter function
registered for that type there.  Converter names are case-sensitive!
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-2553' xml:id='l2h-2553'>PARSE_COLNAMES</tt></b></dt>
<dd>
This constant is meant to be used with the <var>detect_types</var> parameter of the
<tt class="function">connect</tt> function.

<p>
Setting this makes the SQLite interface parse the column name for each column
it returns.  It will look for a string formed [mytype] in there, and then
decide that 'mytype' is the type of the column. It will try to find an entry of
'mytype' in the converters dictionary and then use the converter function found
there to return the value. The column name found in <tt class="member">cursor.description</tt> is only
the first word of the column name, i.  e. if you use something like
<code>'as "x [datetime]"'</code> in your SQL, then we will parse out everything until the
first blank for the column name: the column name would simply be "x".
</dd></dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2554' xml:id='l2h-2554' class="function">connect</tt></b>(</nobr></td>
  <td><var>database</var><big>[</big><var>, timeout, isolation_level, detect_types, factory</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Opens a connection to the SQLite database file <var>database</var>. You can use
<code>":memory:"</code> to open a database connection to a database that resides in
RAM instead of on disk.

<p>
When a database is accessed by multiple connections, and one of the processes
modifies the database, the SQLite database is locked until that transaction is
committed. The <var>timeout</var> parameter specifies how long the connection should
wait for the lock to go away until raising an exception. The default for the
timeout parameter is 5.0 (five seconds). 

<p>
For the <var>isolation_level</var> parameter, please see the <tt class="member">isolation_level</tt>
property of <tt class="class">Connection</tt> objects in section&nbsp;<a href="sqlite3-Connection-Objects.html#sqlite3-Connection-IsolationLevel">13.13.2</a>.

<p>
SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If
you want to use other types, like you have to add support for them yourself.
The <var>detect_types</var> parameter and the using custom <strong>converters</strong> registered with
the module-level <tt class="function">register_converter</tt> function allow you to easily do that.

<p>
<var>detect_types</var> defaults to 0 (i. e. off, no type detection), you can set it
to any combination of <tt class="constant">PARSE_DECLTYPES</tt> and <tt class="constant">PARSE_COLNAMES</tt> to turn type
detection on.

<p>
By default, the <tt class="module">sqlite3</tt> module uses its <tt class="class">Connection</tt> class for the
connect call.  You can, however, subclass the <tt class="class">Connection</tt> class and make
<tt class="function">connect</tt> use your class instead by providing your class for the
<var>factory</var> parameter.

<p>
Consult the section <a href="sqlite3-Types.html#sqlite3-Types">13.13.4</a> of this manual for details.

<p>
The <tt class="module">sqlite3</tt> module internally uses a statement cache to avoid SQL parsing
overhead. If you want to explicitly set the number of statements that are
cached for the connection, you can set the <var>cached_statements</var> parameter.
The currently implemented default is to cache 100 statements.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2555' xml:id='l2h-2555' class="function">register_converter</tt></b>(</nobr></td>
  <td><var>typename, callable</var>)</td></tr></table></dt>
<dd>
Registers a callable to convert a bytestring from the database into a custom
Python type. The callable will be invoked for all database values that are of
the type <var>typename</var>. Confer the parameter <var>detect_types</var> of the
<tt class="function">connect</tt> function for how the type detection works. Note that the case of
<var>typename</var> and the name of the type in your query must match!
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2556' xml:id='l2h-2556' class="function">register_adapter</tt></b>(</nobr></td>
  <td><var>type, callable</var>)</td></tr></table></dt>
<dd>
Registers a callable to convert the custom Python type <var>type</var> into one of
SQLite's supported types. The callable <var>callable</var> accepts as single
parameter the Python value, and must return a value of the following types:
int, long, float, str (UTF-8 encoded), unicode or buffer.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2557' xml:id='l2h-2557' class="function">complete_statement</tt></b>(</nobr></td>
  <td><var>sql</var>)</td></tr></table></dt>
<dd>
Returns <tt class="constant">True</tt> if the string <var>sql</var> contains one or more complete SQL
statements terminated by semicolons. It does not verify that the SQL is
syntactically correct, only that there are no unclosed string literals and the
statement is terminated by a semicolon.

<p>
This can be used to build a shell for SQLite, as in the following example:

<p>
<div class="verbatim">
<pre># A minimal SQLite shell for experiments

import sqlite3

con = sqlite3.connect(":memory:")
con.isolation_level = None
cur = con.cursor()

buffer = ""

print "Enter your SQL commands to execute in sqlite3."
print "Enter a blank line to exit."

while True:
    line = raw_input()
    if line == "":
        break
    buffer += line
    if sqlite3.complete_statement(buffer):
        try:
            buffer = buffer.strip()
            cur.execute(buffer)

            if buffer.lstrip().upper().startswith("SELECT"):
                print cur.fetchall()
        except sqlite3.Error, e:
            print "An error occurred:", e.args[0]
        buffer = ""

con.close()
</pre>
<div class="footer">
<a href="complete_statement.txt" type="text/plain">Download as text (original file name: <span class="file">sqlite3/complete_statement.py</span>).</a>
</div></div>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2558' xml:id='l2h-2558' class="function">enable_callback_tracebacks</tt></b>(</nobr></td>
  <td><var>flag</var>)</td></tr></table></dt>
<dd>
By default you will not get any tracebacks in user-defined functions,
aggregates, converters, authorizer callbacks etc. If you want to debug them,
you can call this function with <var>flag</var> as True. Afterwards, you will get
tracebacks from callbacks on <code>sys.stderr</code>. Use <tt class="constant">False</tt> to disable
the feature again.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.13 sqlite3  "
  href="module-sqlite3.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="13.13 sqlite3  "
  href="module-sqlite3.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="13.13.2 connection Objects"
  href="sqlite3-Connection-Objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sqlite3.html">13.13 sqlite3  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sqlite3.html">13.13 sqlite3  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="sqlite3-Connection-Objects.html">13.13.2 Connection Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
